// -*- tab-width: 4; Mode: C++; c-basic-offset: 4; indent-tabs-mode: nil -*-
/*
   This program is free software: you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation, either version 3 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

// Copyright 2010 Michael Smith, all rights reserved.

// Derived closely from:
/****************************************
* 3D Vector Classes
* By Bill Perone (billperone@yahoo.com)
* Original: 9-16-2002
* Revised: 19-11-2003
*          11-12-2003
*          18-12-2003
*          06-06-2004
*
* 2003, This code is provided "as is" and you can use it freely as long as
* credit is given to Bill Perone in the application it is used in
*
* Notes:
* if a*b = 0 then a & b are orthogonal
* a%b = -b%a
* a*(b%c) = (a%b)*c
* a%b = a(cast to matrix)*b
* (a%b).length() = area of parallelogram formed by a & b
* (a%b).length() = a.length()*b.length() * sin(angle between a & b)
* (a%b).length() = 0 if angle between a & b = 0 or a.length() = 0 or b.length() = 0
* a * (b%c) = volume of parallelpiped formed by a, b, c
* vector triple product: a%(b%c) = b*(a*c) - c*(a*b)
* scalar triple product: a*(b%c) = c*(a%b) = b*(c%a)
* vector quadruple product: (a%b)*(c%d) = (a*c)*(b*d) - (a*d)*(b*c)
* if a is unit vector along b then a%b = -b%a = -b(cast to matrix)*a = 0
* vectors a1...an are linearly dependant if there exists a vector of scalars (b) where a1*b1 + ... + an*bn = 0
*           or if the matrix (A) * b = 0
*
****************************************/
#pragma once

#ifndef VECTOR3_HPP_
#define VECTOR3_HPP_

#include <cmath>
#include <float.h>
#include <string.h>

template<typename T>
class Matrix3;

template<typename T>
class Vector3
{

public:
    T x, y, z;

    // trivial ctor
    Vector3<T>()
    {
        x = y = z = 0;
    }

    // setting ctor
    Vector3<T>(const T x0, const T y0, const T z0) :
            x(x0), y(y0), z(z0)
    {
    }

    // function call operator
    void operator ()(const T x0, const T y0, const T z0)
    {
        x = x0;
        y = y0;
        z = z0;
    }

    //简单运算定义
    // test for equality
    bool operator ==(const Vector3<T> &v) const;

    // test for inequality
    bool operator !=(const Vector3<T> &v) const;

    // negation
    Vector3<T> operator -(void) const;

    // addition
    Vector3<T> operator +(const Vector3<T> &v) const;

    // subtraction
    Vector3<T> operator -(const Vector3<T> &v) const;

    // uniform scaling
    Vector3<T> operator *(const T num) const;

    // uniform scaling
    Vector3<T> operator /(const T num) const;

    // addition
    Vector3<T> &operator +=(const Vector3<T> &v);

    // subtraction
    Vector3<T> &operator -=(const Vector3<T> &v);

    // uniform scaling
    Vector3<T> &operator *=(const T num);

    // uniform scaling
    Vector3<T> &operator /=(const T num);
    //简单运算定义结束

    // allow a vector3 to be used as an array, 0 indexed  使得向量可以作为一维数组使用
    T & operator[](uint8_t i)
    {
        T *_v = &x;
#if MATH_CHECK_INDEXES
        assert(i >= 0 && i < 3);
#endif
        return _v[i];
    }

    const T & operator[](uint8_t i) const
    {
        const T *_v = &x;
#if MATH_CHECK_INDEXES
        assert(i >= 0 && i < 3);
#endif
        return _v[i];
    }

    // dot product 点乘
    T operator *(const Vector3<T> &v) const;

    // multiply a row vector by a matrix, to give a row vector  乘以矩阵
    Vector3<T> operator *(const Matrix3<T> &m) const;

    // multiply a column vector by a row vector, returning a 3x3 matrix 乘以列向量返回3*3矩阵
    Matrix3<T> mul_rowcol(const Vector3<T> &v) const;

    // cross product  向量叉乘
    Vector3<T> operator %(const Vector3<T> &v) const;

    // computes the angle between this vector and another vector 计算两向量夹角
    float angle(const Vector3<T> &v2) const;

    // check if any elements are NAN  检测元素是否为有意义结果
    // NaN()用于检测浮点数是否是负数的平方根或是0/0的结果
    // The NaN values are used to identify undefined or non-representable
    // values for floating-point elements, such as the square root of negative
    // numbers or the result of 0/0.
    bool is_nan(void) const;

    // check if any elements are infinity  检测元素是否趋于无穷(负无穷或正无穷)
    // Returns whether x is an infinity value (either positive
    // infinity or negative infinity).
    bool is_inf(void) const;

    // check if all elements are zero  检测元素是否都为0
    bool is_zero(void) const
    {
        return (fabsf(x) < FLT_EPSILON) && (fabsf(y) < FLT_EPSILON)
                && (fabsf(z) < FLT_EPSILON);
    }

    // rotate by a standard rotation  使用标准矩阵旋转
    void rotate(enum Rotation rotation);
    void rotate_inverse(enum Rotation rotation);

    // gets the length of this vector squared 返回向量的模平方
    T length_squared() const
    {
        return (T) (*this * *this);
    }

    // gets the length of this vector  返回向量的模
    float length(void) const;

    // normalizes this vector  向量的归一化值
    void normalize()
    {
        *this /= length();
    }

    // zero the vector  向量置零
    void zero()
    {
        x = y = z = 0;
    }

    // returns the normalized version of this vector  返回向量的归一化值
    Vector3<T> normalized() const
    {
        return *this / length();
    }

    // reflects this vector about n  沿着n向量的方向将向量反向
    void reflect(const Vector3<T> &n)
    {
        Vector3<T> orig(*this);
        project(n);
        *this = *this * 2 - orig;
    }

    // projects this vector onto v   将向量投影在V向量上的
    void project(const Vector3<T> &v)
    {
        *this = v * (*this * v) / (v * v);
    }

    // returns this vector projected onto v  返回向量在V向量上的投影
    Vector3<T> projected(const Vector3<T> &v) const
    {
        return v * (*this * v) / (v * v);
    }
};

typedef Vector3<int16_t> Vector3i;
typedef Vector3<uint16_t> Vector3ui;
typedef Vector3<int32_t> Vector3l;
typedef Vector3<uint32_t> Vector3ul;
typedef Vector3<float> Vector3f;
typedef Vector3<double> Vector3d;

#endif /* VECTOR3_HPP_ */
